/*
* File: som_supervised_optimizer.h
* @Brief: the functions about supervised optimization method.
* @Author: Mr.Charley(Chinese name: Chenglin Jia).
* @Version: 1.0
* @Date: 2024/7/22
*/

#ifndef SOM_SUPERVISED_OPTIMIZER_H
#define SOM_SUPERVISED_OPTIMIZER_H

#include "som_linear_regressor.h"

// The struct of Som_Supervised_Optimizer.
// the function pointer of Project Function.

typedef CvMat* (*ProjectFunc)(const CvMat* parameters, const int regressor_level, const int training_index);

// the function pointer of Normalize Function
typedef CvMat* (*Som_Normalized_Func)(const CvMat* params);

struct Som_Supervised_Optimizer_
{
	Som_Linear_Regressor** som_linear_regressors;	// stores the linear regressors.
	Som_Normalized_Func som_normalized_func;	// the normalized method.
	int num_regressors;	// the number of regressors.
};

typedef struct Som_Supervised_Optimizer_ Som_Supervised_Optimizer;


/************************************************************************/
/*
 * @brief The strategy of normalization. Non-normalization will be used in this application.
 * @param[in] params: It will be used to generate properly normalization matrix.
 * @return Return normalization matrix.
 */
 /************************************************************************/
SOM_EXPORT CvMat* no_normal_func(const CvMat* params);

/************************************************************************/
/*
 * @brief create a som_supervised_optimizer object.
 * @param[in] som_linear_regressors[]: The linear regressors' pointer point into a set of linear regressors.
 * @param[in] som_normalizer: The function of normalizer. If the pointer is null, no_normal_func will be used, it stand for there isn't normalize.
 * @param[in] num_regressors: The number of linear regressors.
 * @return Return the Som_Supervised_Optimizer object.
 */
 /************************************************************************/
SOM_EXPORT Som_Supervised_Optimizer* som_supervised_opimizer_new(const Som_Linear_Regressor* som_linear_regressors[], const Som_Normalized_Func som_normalized_func, const int num_regressors);

/************************************************************************/
/*
 * @brief delete the som_supervised_optimizer object.
 * @param[in] som_supervised_optimizer: The Som_Supervised_Optimizer object wanted to be deleted.
 * @return Return void.
 */
 /************************************************************************/
SOM_EXPORT void som_supervised_optimizer_delete(Som_Supervised_Optimizer* som_supervised_optimizer);

/************************************************************************/
/*
 * @brief train the regressors model by given training data.
 * @param[in&&out] som_supervised_optimizer: The SOM model include linear regressors and normalization method.
 * @param[in] parameters: The truth or known value. for example ground landmarks in face alignment, or known coordinate of point in image plane in space resection.
 * @param[in] initializations: The initial value, for example, the landmark by initialed by OpenCV face detector, or the coordinate in image plane under current element exterior orientation.
 * @param[in] teamples: A optional parameter, for example, the HOG feature of the ground landmarks
 * @param[in] projectfunc: The project function, such as, 3D space into 2D space, or the HOG features space
 * @param[in] on_training_epoch_callback The pointer point into function.
 * @return Return void.
 */
 /************************************************************************/
SOM_EXPORT void som_supervised_optimizer_train(Som_Supervised_Optimizer* som_supervised_optimizer, const CvMat* parameters, const CvMat* initializations,
	const CvMat* teamples, ProjectFunc projectfunc, void(*on_training_epoch_callback)(CvMat*, CvMat*));

/************************************************************************/
/*
 * @brief predict a single example by learned regressors model.
 * @param[in] som_supervised_optimizer: The SOM model obtain by learning.
 * @param[in] initializations: The initial value for parameter.
 * @param[in] teamples: see the more detail from the som_supervisedoptimizer_train.
 * @param[in] projectfunc: The project function that projecting the space of parameter into the space of temples value. for example, 3D into 2D, or HOG feature space.
 * @return Return the predicted value.
 */
 /************************************************************************/
SOM_EXPORT CvMat* som_supervised_optimizer_predict(const Som_Supervised_Optimizer* som_supervised_optimizer, const CvMat* initializations, const CvMat* templates, ProjectFunc projectfunc);

/************************************************************************/
/*
 * @brief Tests the learned regressors model with the given test data.
 * @param[in] som_supervised_optimizer: The learned regressors model.
 * @param[in] parameters: The truth or known value. for example ground landmarks in face alignment, or known coordinate of point in image plane in space resection.
 * @param[in] initializations: The initial value, for example, the landmark by initialed by OpenCV face detector, or the coordinate in image plane under current element exterior orientation.
 * @param[in] teamples: A optional parameter, for example, the HOG feature of the ground landmarks.
 * @param[in] projectfunc: The project function, such as, 3D space into 2D space, or the HOG features space.
 * @param[in] on_training_epoch_callback: The pointer point into function.
 * @return Return the predicted value.
 */
 /************************************************************************/
SOM_EXPORT CvMat* som_supervised_optimizer_test(const Som_Supervised_Optimizer* som_supervised_optimizer, const CvMat* parameters, const CvMat* initializations,
	const CvMat* teamples, ProjectFunc projectfunc, void(*on_training_epoch_callback)(CvMat*, CvMat*));

/************************************************************************/
/*
 * @brief Write the object Som_Supervised_Optimizer into the file given.
 * @param[in] fp: The pointer of FILE to the file want to write in.
 * @param[in] som_supervised_optimizer: The object Som_Supervised_Optimizer want to write in.
 * @return Return void.
 */
 /************************************************************************/
SOM_EXPORT void write_som_supervised_opimizer_into_file(FILE* fp, const Som_Supervised_Optimizer* som_supervised_optimizer);

/************************************************************************/
/*
 * @brief Read the object Som_Supervised_Optimizer from the file.
 * @param[in] fp: The pointer of FILE to the file want to write in.
 * @param[in&out] som_normalized_func: The object Som_Supervised_Optimizer.
 * @param[in] som_normalizer: The function of normalizer. If the pointer is null, no_normal_func will be used, it stand for there isn't normalized.
 */
 /************************************************************************/
SOM_EXPORT void read_som_supervised_opimizer_from_file(FILE* fp, Som_Supervised_Optimizer** som_supervised_optimizer, const Som_Normalized_Func som_normalized_func);


#endif // !SOM_SUPERVISED_OPTIMIZER_H
